Review — mechanism is solid, the challenge is on the default policy and repair cost

Both features are well designed and unusually well tested (the edge cases that normally slip through here — null-candidate never erasing, judge-omitted candidate staying UNCERTAIN, compact array evidence, validator-only path — are all covered). The direction is right. My challenge is not on the code but on (a) the env_template default policy and (b) the real cost of repair on page-heavy documents.

I verified the funnel claim directly: judge_escalator._count_failures() reads the current extracted_groups, and repair mutates them in place with fresh PASS verdicts before escalation runs — so "the expensive full re-run only fires when targeted repair was not enough" is true, not just narrative.

Feature 1 — per-stage model routing

Clean implementation, and usage.by_model is exactly the observability we needed to govern spend per tier.

The shipped env_template only spends the new lever upward. It sets sonnet as the floor for every stage (including mechanical ones) and opus for judge — so as delivered it raises cost rather than optimizing it:

Concrete numbers from our last PROD window (Jul 7-8, 1594 pages): main pipeline was $28.32 all-sonnet (judge ~$11.65) and bbox_refine was $33.30 (the biggest bucket). Pinning judge to opus (~5× per token) takes the judge to ~$55-58 on its own — roughly doubling the main-pipeline bill. Meanwhile FLYDOCS_BBOX_MATCHER_MODEL governs the LlmValueMatcher in bbox_refine, which is value matching against a region (not extraction) and a natural haiku candidate — ~$20-25/window left on the table.

Suggested tiering: splitter / classifier / bbox_matcher → haiku; extract → sonnet; judge → opus only after measuring the detection lift via by_model. That nets a cost reduction.

Also worth documenting for backend consumers: "pinned wins over options.model" means a per-request options.model=cheap cannot lower a pinned-opus judge. Defensible, but surprising.

Feature 2 — closed-loop targeted repair

Right technique, and the monotonic accept guard is careful work. Three things to address before a broad rollout:

1. The "focused" pass does not reduce input, which is the dominant cost. extract_repair is called with document_bytes=task.slice_bytes — the full segment slice, all pages. The focus is on the schema subset, not on the pages. For multimodal docs the input (pages) dominates — that's exactly why per-page bbox_refine was the largest bucket. Repairing 2 fields in a 50-page scanned legajo re-sends all 50 pages, so "a fraction of the cost" holds vs escalation but is overstated for page-heavy docs. ExtractedField.page is available and slice_pdf/PageRange already exist — slicing to the failing fields' pages would make repair cheap for real.

2. No cap on repair scope → worst case is more expensive than before. If most fields fail, the subset ≈ the whole document and repair degenerates into a full re-extract on opus plus a full judge re-check on opus, and escalation can still fire afterward. For an all-fail doc the new path costs more than the old judge→escalation path. A threshold ("if >X% of fields failed, skip targeted repair and go straight to escalation") removes that pathological case; targeted repair only pays off for a minority of failing fields.

3. Monotonicity is weaker for array/table fields. Arrays are repaired whole: if one row's value fails, the entire array field is re-extracted and, if it passes validation, replaces the original array — including rows that were previously correct. The accept guard is at the array-field level, not the row level, so a previously-correct row can change and slip through if the change still passes validators. "Can only improve, never degrade" is not strictly true for tables — which is our bastanteo apoderados/socios case. Not a code bug, but a QA item: diff correct rows before/after on table fields.

Minor: flag_for_review PASS fields get sent to repair (often ambiguous-but-correct → cost leak, though the guard prevents degradation); repair_timeout_s=300 exceeds FLYDOCS_SYNC_TIMEOUT_S=60 so a sync caller enabling repair blows the sync budget; given the recent 429/OOM history I'd bound repair concurrency on rollout and watch by_model.

Suggested sequencing

Ship routing first (low risk, immediate observability/cost benefit) with the corrected tiering, then repair (opt-in, larger surface) with page-slicing and a scope threshold. Neither change touches the PR's architecture.

Thanks — every point actioned in #43 (feat/pr42-review-fixes → demo), which will flow into this PR once merged. No architecture changes.

Routing: env_template now nets a cost reduction — mechanical stages (splitter/classifier/bbox_matcher) → haiku, extract → sonnet, judge → opus documented as opt-in after measuring lift via by_model. Stage-pin-wins-over-options.model documented.

Repair: (2.1) page-slices to the failing fields' pages via ExtractedField.page so a 2-field fix in a 50-page legajo no longer re-sends 50 pages; (2.2) repair_max_failing_fraction skips targeted repair and goes straight to escalation past a threshold, killing the >X%-fail pathological case; (2.3) RepairInfo.rows_changed surfaces whole-array row changes (bastanteo apoderados/socios QA case). Plus repair_include_flagged (keep ambiguous PASS fields out), repair_sync_latency warning (300s repair vs 60s sync budget), and repair_task_concurrency for the 429/OOM history.

336 unit tests green, ruff clean.